home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_amanda.idb / usr / freeware / doc / amanda / INTERNALS.z / INTERNALS
Encoding:
Text File  |  1999-07-16  |  7.9 KB  |  219 lines
  1. This is an attempt to document Amanda's internals.  Please feel free to make
  2. comments and suggest changes.  Text for new sections gratefully accepted!
  3.  
  4. George.
  5. (George.Scott@cc.monash.edu.au)
  6.  
  7. ===============
  8. == PROTOCOLS ==
  9. ===============
  10.  
  11.  
  12.       Client I Server         +-planner-+
  13.              I                |         |
  14.              I                |         |
  15.              I                |         |                     ______
  16. +-amandad-+  I                |         |                    (______)
  17. |         |  I                |         |                    |amdump|
  18. |         |  I                |         |           all ::::>|      |
  19. |         |  I                |         |           stderr   |      |
  20. |         |  I                |         |                    |      |
  21. |         |  I                |   so    |                    +------+
  22. |         |  I                +---------+
  23. |         |  I                    ::                          ______
  24. |         |  I                    \/                         (______)
  25. |         |  I                +-driver--+                    | log  |
  26. +---------+  I                |   si    |           all ::::>|      |
  27.              I                |         |           log      |      |
  28.              I                |         |                    |      |
  29. +-sendback+  I                |         |                    +------+
  30. |         |  I                |         |
  31. |         |  I        ::::::::|         |<::::::
  32. |         |  I       ::       |         |      ::
  33. |         |  I      ::   ::::>|         |::::   ::
  34. |         |  I      ::  ::    |         |   ::  ::
  35. |         |  I      :: ::     +---------+    :: ::
  36. |         |  I      :: ::                    :: ::
  37. |         |  I      :: ::                    :: ::
  38. |         |  I      :: ::       ______       :: ::
  39. +---------+  I      :: ::      (______)      :: ::
  40.              I      :: ::      | /tmp |      :: ::
  41.              I      \/ ::    :>|      |      \/ ::
  42. +-dump----+  I  +-dumper--+ :: +------+    +-taper/r-+    +-taper/w-+
  43. |         |  I  |   si so | ::             | si so   |    |         |
  44. |         |  I  |         | ::  ______     |         |    |         |
  45. |         |  I  |mesgfd   | :: (______)    |         |    |         |
  46. |       se|::::>|::::::::>|::  | hold |    |         |    |         |
  47. |         |  I  |     errf|    | disk |    |      p2c|:::>|p2c      |
  48. |         |  I  |         |    |      |    |      c2p|<:::|c2p      |     ____
  49. |         |  I  |datafd   | ::>|      |::: |fd       |    |         |   /   \
  50. |       so|::::>|::::::::>|::  +------+  :>|::::::::>SHDMEM::::::::>|::>|tape|
  51. |         |  I  |    outfd| ::          :: |         |    |   tapefd|   \ _ /
  52. +---------+  I  +---------+  ::::::::::::  +---------+    +---------+      
  53.              I
  54.  
  55.  
  56. server and amandad on client
  57. ============================
  58.  
  59. XXX - still to be done
  60.  
  61.  
  62. planner and driver
  63. ==================
  64.  
  65. Planner interrogates all clients and generates a plan of which disks to
  66. backup and what dump level to do them at.  The plan is plain text with one
  67. line per disk to be dumped.  It is piped from planners stdout to drivers
  68. stdin.  Plan lines come in two flavours:
  69.  
  70. For total dumps:
  71.    <host> <disk> <pri> <lev> <size> <time> <deg lev> <deg size> <deg time>
  72.  
  73. For incremental dumps:
  74.    <host> <disk> <pri> <lev> <size> <time>
  75.  
  76. Where:
  77.    <host>      Host name of client (from disklist file)
  78.    <disk>      Name of disk (from disklist file)
  79.    <pri>       Priority of backup (pri from disklist and amanda.conf + days
  80.                  overdue for total)
  81.    <lev>       Dump level for dump (0 for total, 1-9 for incremental)
  82.    <size>      Estimated size (in Kb after compression if requested)
  83.    <time>      Estimated time for backup (in seconds)
  84.    <deg lev>   <lev> to use if in degraded mode
  85.    <deg size>  <size> to use if in degraded mode
  86.    <deg time>  <time> to use if in degraded mode
  87.  
  88.  
  89. driver and dumper
  90. =================
  91.  
  92. Driver talks via two pipes connected to each dumper's stdin and stdout.  The
  93. commands and responses are plain text.
  94.  
  95. Driver can ask dumper to do a dump to a file on the holding disk:
  96.    FILE-DUMP <handle> <filename> <host> <disk> <level> <prog> <options>
  97. or directly to taper:
  98.    PORT-DUMP <handle> <port> <host> <disk> <level> <prog> <options>
  99. or exit at the end of the run:
  100.    QUIT
  101.  
  102. If the dump finishes correctly dumper replies with:
  103.    DONE <handle> [<message>]
  104.  
  105. If something goes wrong with the dump, dumper can request that the dump be
  106. retried at a later time with:
  107.    TRY-AGAIN <handle> [<message>]
  108. or, for fatal errors, be abandoned with:
  109.    FAILED <handle> [<message>]
  110.  
  111. If the holding disk runs out of space, dumper will give:
  112.    NO-ROOM <handle>
  113. and wait for driver to either fix the problem and say:
  114.    CONTINUE
  115. or just say:
  116.    ABORT
  117. in which case dumper kills the dump and replies with:
  118.    ABORT-FINISHED <handle>
  119.  
  120. If driver says something that dumper doesn't recognise it responds with:
  121.    BAD-COMMAND <message>
  122.  
  123. Where:
  124.    <handle>    Request ID
  125.    <filename>  Name of file (on holding disk) to write dump
  126.    <port>      Port (of taper) to send dump directly
  127.    <host>      Hostname of client
  128.    <disk>      Disk to backup
  129.    <level>     Dump level to do backup at
  130.    <prog>      Dump program to use
  131.    <options>   Options to pass to sendbackup
  132.    <message>   Error or status message
  133.  
  134.  
  135. driver and taper
  136. ================
  137.  
  138. Driver talks via two pipes connected to taper's stdin and stdout.  The
  139. commands and responses are plain text.
  140.  
  141. Driver initialises taper with:
  142.    START-TAPER <datestamp>
  143. to which taper replies with:
  144.    TAPER-OK
  145. or, for fatal errors, with:
  146.    TAPER-ERROR [<message>]
  147.  
  148. Driver can ask taper to to copy a file from the holding disk to tape:
  149.    FILE-WRITE <handle> <filename> <host> <disk> <level>
  150. or directly from a dumper:
  151.    PORT-WRITE <handle> <host> <disk> <level>
  152. or exit at the end of the run:
  153.    QUIT
  154.  
  155. Taper responds to the PORT-WRITE command with:
  156.    PORT <port>
  157. which driver should then hand on to dumper in a PORT-DUMP command.
  158.  
  159. Taper responds to the QUIT command with:
  160.    QUITING
  161.  
  162. If the copy to tape finishes correctly taper replies with:
  163.    DONE <handle> [<message>]
  164.  
  165. If something goes wrong with the tape, taper can request that the dump be
  166. retried at a later time with:
  167.    TRY-AGAIN <handle> [<message>]
  168. or, for fatal errors, be abandoned with:
  169.    TAPE-ERROR <handle> [<message>]
  170.  
  171. If driver says something that taper doesn't recognise it responds with:
  172.    BAD-COMMAND <message>
  173.  
  174. Where:
  175.    <datestamp> Todays date as "yymmdd"
  176.    <handle>    Request ID
  177.    <filename>  Name of file (on holding disk) to write dump
  178.    <port>      Port (of taper) to send dump directly
  179.    <host>      Hostname of client
  180.    <disk>      Disk to backup
  181.    <level>     Dump level to do backup at
  182.    <message>   Error or status message
  183.  
  184.  
  185. taper(read) and taper(write)
  186. ============================
  187.  
  188. There are two parts to taper: the file reader and the tape writer.
  189. Communication between the two sides is via a bit of shared memory for data
  190. transfer and two pipes (one in each direction) for synchronisation.
  191.  
  192. The shared memory area is made up of NBUFS (=20) buffers each of which
  193. contains a status word and a BUFFER_SIZE (=32*1024) byte data buffer.
  194.  
  195. The sync pipes are used to transfer a simplistic command sequence:
  196.  
  197. reader                              writer
  198. ------                              ------
  199.  
  200. Startup           S<datestamp> --->
  201.                                <--- S             Start OK
  202.                                <--- E<messge>     Error
  203.  
  204. Open tape         O            --->
  205.                                <--- O             Opening
  206.  
  207. Write buffer      W<bufnum>    --->
  208.                                <--- R<bufnum>     Buffer empty
  209.                                <--- E<message>    Error
  210.                                <--- T<message>    Error, try again
  211. E ack             e            --->
  212. Protocol error    X            --->
  213.                                <--- x             X ack
  214.  
  215. Close tape        C            --->
  216.                                <--- C<label><filenum><stats>  Closing
  217.  
  218. Quit              Q            --->
  219.